Implement the async Clipboard API (navigator.clipboard) - #33312

✅ @robobun, your commit 78695f47481eba5534d2cf230cae6c49fb092c45 passed in Build #126809! 🎉

🧪   To try this PR locally:

bunx bun-pr 33312

That installs a local version of the PR into your bun-33312 executable, so you can run:

bun-33312 --bun

Preview deployment for your docs. Learn more about Mintlify Previews.

💡 Tip: Enable Workflows to automatically generate PRs for you.

Walkthrough

Adds Clipboard, ClipboardItem, and ClipboardEvent support across Bun's typings, parser globals, WebCore/JSC bindings, native clipboard backends, runtime wiring, documentation, and tests.

Changes

Clipboard API implementation

Suggested reviewers: alii

Pre-merge checks: 4

Passed checks: 4 passed

Check name	Status	Explanation
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.
Description check		The description clearly explains the Clipboard API implementation, architecture, platform behavior, limitations, and extensive test coverage. It uses different headings from the template, but it provi…
Title check		The title clearly and concisely identifies the primary change: implementing the asynchronous Clipboard API through navigator.clipboard.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

_{Comment @coderabbitai help to get the list of available commands.}

All three addressed in 8ff1962.

No JSNativeStdFunction, no chaining. write() is a resumable loop over the item's representations instead of an N-deep .then() chain, and both it and ClipboardItem.getType() now register shared, non-capturing host functions through performPromiseThenWithContext — the same reaction convention the streams code uses (handler(value, contextCell), context at argument(1)). Grep for JSNativeStdFunction, Strong<, or ->then( in JSClipboard.cpp / JSClipboardItem.cpp and all three are zero.

One strong, in the returned promise. The state the lambdas used to capture lives in a context cell whose fields are visited — JSClipboardWriteState for write(), an InternalFieldTuple{item, index} for getType() — so the C++ side holds none at all. The last one was structural: C++ had to chain its promise onto the one Rust created. Bun__Clipboard__writeBlobs now takes the promise write() already returned and the scheduled job settles it, leaving that job's JSPromiseStrong as the only strong handle involved.

One behaviour change worth surfacing: only an object can be a thenable, so string representations normalize inline now and cost no reaction — getType() on a string resolves a tick earlier than on a Blob representation of the same item. Nothing pins that ordering; happy to route strings through a reaction too if you'd rather they stay uniform.

On CI: the red windows-11-aarch64 - test-bun was test/js/sql/postgres-{binary-array-bounds,invalid-message-length} — this branch predated #33962, the flake fix for exactly those two files. Merged main in 82b761a and those are green now.

That shard is still red on a different one: bun-install-registry > hoisting > peers > it should hoist 1.0.1 when peer *. This branch touches no install/resolver/lockfile code and the same shard is failing concurrently on unrelated PRs, so I don't think it's this change — but it's Windows-only and verdaccio-backed, so I couldn't reproduce it locally to prove that. A retry of that one job would settle it.

@robobun adopt it

@robobun thanks, the before/after numbers for read_types are exactly what that change needed.

On the two open questions:

• Message-only window for OpenClipboard: a follow-up PR after this merges, not here. The finding is real (NULL does not exclude another NULL opener, in any process), and a clipboard window is what browsers use. But it is new Win32 surface that nobody reviewing this PR has asked for, the last maintainer review asked for less cross-operation machinery, not more ("isn't that a concern for userland code?"), and this head is green and waiting on re-review. Please keep the branch and the two-process repro; it makes a good self-contained PR with its own test.
• dib_as_bmp length check: not needed. It only matters for a bitmap that starts with the three mask values as pixels.

Please do not push to this branch for either.

One CI note for build 119414 on 45942c1: the only job that did not pass is Windows 11 aarch64 - test-bun shard 4 of 8, which was cancelled because its agent could not be created ([azure] Operation timed out after 600000ms). No test failed; the other seven arm64 shards and all eight x64 shards passed.

@cirospaciari understood. I push nothing to this branch, and I drop the dib_as_bmp length check.

The window change waits for the merge. It is on robobun/3735dc8f/clipboard-window (ed138e4, one commit on top of 45942c1), and I open the follow-up PR from it after this PR merges. The commit has its own test, which does not depend on timing: the test holds the clipboard open with no window, as a console program does, and calls writeText(). Without the change, writeText() resolves, the text is replaced, and the holder's CloseClipboard fails. With the change, writeText() rejects with NotAllowedError, the holder still owns the open clipboard, and its text is intact. On windows-x64 the test fails before and passes after, and the file has 62 pass and 0 fail.

// One of two processes that use the clipboard at the same time through the
// public API only. Every value a read returns must be one that a write produced.
const id = process.argv[2];
const until = performance.now() + Number(process.argv[3] ?? 3000);
const stats = { id, writes: 0, reads: 0, writeRejected: {}, readRejected: {}, emptyReads: 0, foreignReads: 0, tornItems: 0 };
const png = new Blob([Buffer.from("iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR4nGP4z8DQDwAEgAF/pooBPQAAAABJRU5ErkJggg==", "base64")], { type: "image/png" });
let i = 0;
while (performance.now() < until) {
  const text = `p${id}-${i++}`;
  try {
    await navigator.clipboard.write([new ClipboardItem({ "text/plain": text, "text/html": `<b>${text}</b>`, "image/png": png })]);
    stats.writes++;
  } catch (e) {
    stats.writeRejected[e.message] = (stats.writeRejected[e.message] ?? 0) + 1;
  }
  try {
    const items = await navigator.clipboard.read();
    stats.reads++;
    if (items.length === 0) stats.emptyReads++;
    else {
      const types = [...items[0].types].sort().join(",");
      // Both processes always write all three types in one write().
      if (types !== "image/png,text/html,text/plain") stats.tornItems++;
      else {
        const plain = await (await items[0].getType("text/plain")).text();
        const html = await (await items[0].getType("text/html")).text();
        if (!/^p[ab]-\d+$/.test(plain)) stats.foreignReads++;
        else if (html !== `<b>${plain}</b>`) stats.tornItems++;
      }
    }
  } catch (e) {
    stats.readRejected[e.message] = (stats.readRejected[e.message] ?? 0) + 1;
  }
}
console.log(JSON.stringify(stats));

@cirospaciari this PR now conflicts with main. I did not push anything: you asked me not to push to this branch, so the merge is yours, or mine if you say so.

The conflict. There is one, in src/runtime/image/codecs.rs, inside impl Encoded. It comes from #44086 (a7c73fd).

• This branch added as_slice (#[cfg(windows)]) above from_owned, and from_owned kept #[allow(dead_code)].
• Main replaced that attribute on from_owned with #[cfg(any(target_os = "macos", windows))].
• Resolution: keep as_slice, and take the attribute from main for from_owned.

impl Encoded {
    #[cfg(windows)]
    pub(crate) fn as_slice(&self) -> &[u8] {
        // SAFETY: `bytes` is a live allocation owned by `self` until `Drop`.
        unsafe { self.bytes.as_ref() }
    }

    #[cfg(any(target_os = "macos", windows))]
    pub(crate) fn from_owned(bytes: Vec<u8>) -> Encoded {

What I checked with that merge, locally (45942c1 merged with main at a4f1429):

• The diff against main is the same as before the merge: 50 files, 6503 insertions, 204 deletions.
• cargo check --workspace passes for x86_64-pc-windows-msvc, aarch64-apple-darwin, x86_64-unknown-freebsd, aarch64-linux-android and x86_64-unknown-linux-gnu. No warning names a file of this PR. That matters because Say the platform once: real #[cfg] in place of stubs, placeholders, let _ = x and allow(...) #44086 removed the allow(dead_code) escapes, so dead_code now sees all of bun_runtime.
• test/internal/source-lints passes.
• Linux debug build, test/js/web/clipboard/clipboard.test.ts: 49 pass, 0 fail. With CI=1 and BUN_JSC_validateExceptionChecks=1: 57 pass, 0 fail. My machine was under heavy load, so I ran the file with a 120 s test timeout.

I could not run Windows this time. The Windows lanes in CI are the check for the Win32 tests after the merge.

@robobun fix conflicts and rebase

@robobun adopt again this PR

@cirospaciari done. The branch has no conflict with main now, and I drive this PR again.

• d28ff32 merges main (a4f1429) into the branch. The one conflict, in src/runtime/image/codecs.rs, has the resolution from my last comment. The checks in that comment are for this exact tree.
• I merged and did not rebase. The branch has 122 commits that are not on main, and 23 of them are merges of main. A rebase replays the other 99 without the conflict resolutions that those merges hold, and it needs a force push over the history that your checkout has. The PR is squash-merged, so the commit on main is the same in both cases. If you want a linear branch all the same, tell me and I do it.
• Windows is the one platform I could not run for this merge. I read the Windows lanes of the CI run for d28ff32 when they finish.

The window change for OpenClipboard stays a follow-up PR after the merge, as you decided.

@cirospaciari I pushed three commits. They are for two defects in the Linux backend at d28ff32. One decision in them is yours, so I name it first.

Your decision: the watchdog

On 2026-09-15 you wrote that the watchdog stays because spawn_sync has no timeout. Commits 2 and 3 give spawn_sync a timeout and remove the watchdog. Two shapes end the hang of defect 2:

I took A because the review of 2026-09-15 named the missing timeout as the cause of the shell string, and because B leaves the other three rows as they are. The cost of A is in shared code. A caller that sets no time limit makes the same system calls as before: 180 of 180 traces are identical.

If you prefer B in this PR and A as a follow-up PR after the merge, say so. Then I replace commits 2 and 3 with the one line.

The defects

1. readText() aborts the process on large text. Text of 1 GiB or more that is not all ASCII aborts with no message. Any text of 2 GiB or more aborts with ASSERTION FAILED: string.size() <= String::MaxLength. A stand-in xclip that prints 1 GiB reproduces it (exit 134).
2. A helper that ignores SIGTERM is never ended. readText() and writeText() never settle, because the watchdog sends only SIGTERM.

The commits

• 96de433301: readText() rejects text that does not fit a string. It stands alone. With only this commit the file passes (51 pass, 0 fail).
• 8cfe6b5e8d: opt-in Options::timeout and Options::linux_pdeathsig in sync::spawn.
• cb80b73428: the backend finds the helper on PATH and runs it directly. BUN_INTERNAL_CLIPBOARD_HELPER_TIMEOUT is gone.
• e46e2a181b and 94e7f1f07c (added after the first review of the push): SyncStdio::Fd is documented and asserted as for stdin only, the waits in the helper tests have a bound, and the test with a real 1 GiB payload is removed because it is too slow for CI.

What changes for users with A

• The helper leads its own process group. A signal to the process group of Bun no longer reaches the daemon that xclip or wl-copy leaves behind.
• An empty PATH finds no helper. The shell searched the working directory.
• A helper script with no #! line fails with "could not be started". spawn: retry via /bin/sh when exec returns ENOEXEC #31717 adds that retry to the spawn.
• When Bun is killed, the kernel ends the helper of a read. The hung helper of a write stays, because the limit lives in the Bun process.
• A read in a worker that is terminated starts no further helper. A write still tries its next helper.

Not in this push

• JobContext::cancel, which the same review asked for. worker.terminate() still waits for the helper run in flight, up to 10 seconds.
• The permission model, and navigator.clipboard = mock that now throws. Both are in the PR body under Downsides for a maintainer decision. I changed no code for them.

Verified

• Linux x64 debug, bun bd test test/js/web/clipboard/clipboard.test.ts at 94e7f1f07c: 62 pass, 31 skip, 0 fail. At cb80b73428 with CI=1 and BUN_JSC_validateExceptionChecks=1: 71 pass, 23 skip, 0 fail. CI build 122957 passed on 94e7f1f07c.
• Ten of the new test cases fail on d28ff32. Three more pass there and pin a clause of the new code. With the clause removed, each of them fails.
• bun run rust:check-all for Windows x64, macOS arm64, FreeBSD x64 and Android arm64: ok. Source lints: 170 pass.
• Not run by me: Windows and macOS. CI is the check for them.

The measurements and the limits that stay are in the Notes block of the PR body.

@cirospaciari the branch had a conflict with main again. It is merged and pushed. The head is c0eff53.

The merge (5dfb92d, main at 281698a)

• One textual conflict, in src/spawn/process.rs. Main added SyncStdio::Pipe(Fd) (Add bun lint and bun format #44805) for the same purpose as SyncStdio::Fd(Fd) of this PR. I took the variant of main and removed ours. clipboard.rs now passes the payload as SyncStdio::Pipe, and the debug assertion from e46e2a1 names Pipe.
• One conflict that git did not see. Main removed setSubclassStructureIfNeeded (DOM constructors: read new.target.prototype before X::create() #45008), so JSClipboardItem.cpp and JSClipboardEvent.cpp did not compile. They now call structureForNewTarget before create(), as the other DOM constructors on main do (92a8769). I checked by hand that class extends, Reflect.construct with a new target, and a prototype getter that throws behave as before.

Two more commits

• f2a7869 answers the last review nit. The helper spawn no longer changes to "." in the child. For a user who is not root, that call fails with EACCES when the working directory has lost its search permission, and the operation then rejected with "No clipboard helper was found". This has no automated test: it needs a user who is not root, and the machine I test on runs as root. I checked it by hand as uid 65534.
• c0eff53 changes tests only. The tests for the time limit and for text that is too large now set their hook in the test process and call the clipboard there. In a debug build a child needs about 1.5 seconds to load bun:internal-for-testing, and 10 children that load it at once need 4 to 7 seconds each. With that, the hung-helper tests reached the 5 second limit of a test on an idle machine. One test keeps its child, because it needs a process without pidfd and memfd.

Verified at c0eff53 (Linux x64, debug build)

• bun bd test test/js/web/clipboard/clipboard.test.ts: 62 pass, 31 skip, 0 fail, in three runs.
• The same file with CI=1, BUN_JSC_validateExceptionChecks=1 and --timeout 120000: 70 pass, 23 skip, 0 fail. With the default timeout one worker test timed out once in that mode.
• bun run rust:check-all for Windows x64, macOS arm64 and FreeBSD x64: ok.
• Source lints: 178 pass. bun-types: 22 pass. run-propagate-sigkill, test-changed and bun-pm-version: 48 pass.
• Not run by me: Windows and macOS. CI is the check for them.

The decision from my earlier comment is still open: the time limit in the spawn (pushed), or kill -9 in the watchdog string with the spawn limit as a follow-up PR. It is in #33312 (comment).